dotbot: report every robot a camera sees, paced to a share of a core - #300

The camera detector used to report one robot per frame. It now fits every robot-shaped candidate on a frame and names each from the robots' lighthouse (LH2) fixes, reporting up to camera_max_robots of them (2 by default). Robots whose fix stands on a candidate are kept first. The console draws every camera robot and its heading, on the map and in the inspector.

Detection rate held to a share of a core

Detection cost grows with the number of robots on the frame, so a fixed rate either wastes the idle case or saturates the busy one. The detector now measures its own cost (smoothed) and schedules the next run so that it holds, on average, camera_detect_share of one core (0.4 by default): rate = share / cost, capped at 10 Hz and floored at 0.5 Hz. The rate falls as robots are added or the machine gets busy and recovers when either goes away.

Measured cost on a real bench frame:

OpenCV runs some of this multithreaded, so process CPU is about 1.2x the wall time measured here; the share is a wall-time budget, not an exact CPU cap.

Both knobs are [controller] config keys and dotbot run controller flags (--camera-max-robots, --camera-detect-share), bounded to >= 1 and (0, 1].

Naming robots correctly

Review of the first cut turned up ways two robots could swap or copy names, fixed here:

• Whole-set matching. Fixes are matched to candidates as one assignment instead of greedily nearest-first. Greedy pairing let a lagging fix take its neighbour's candidate and left the neighbour's fix to split it, so the two robots swapped names. A fix that lands on a component too small for two robots now names nothing instead of copying its host's pose.
• Stale fixes and silent robots. A robot is only marked lost after 60 s of silence, and until then its last fix could name whichever robot now stands where it was. Only fixes from the last 2 s, from robots still advertising, name a candidate.
• Atomic position read. Each fix is read once per frame, since another thread replaces the position whole.
• Config bounds on the two new keys, so a bad value fails at load rather than inside the detector.

Frame capture time

Each part of the MJPEG camera stream now carries an X-Timestamp header, the time the frame was read off the device. A reader slower than the stream builds a backlog in the socket buffers that can be seconds deep, and stamping on receipt hides it; with the capture time a reader can age each frame and drop stale ones.

Breaking change

A camera detection record carries robots, a list of {address, status, timestamp, pose}, in place of the single pose. The camera CSV writes one row per robot with cam_address, cam_status and cam_timestamp under schema_version 2, so an older log is not appended to. Anything reading the old pose field or the schema 1 CSV needs updating.

Changes

Validation

• dotbot/tests pass, including new tests for the matcher, the rate controller, the service and the CSV schema. The only local failures are environment ones unrelated to this branch (a user config file present, port 8000 taken).
• Console: tsc --noEmit, eslint, vitest (578 tests) and vite build pass.
• Tested live on the bench on 2026-09-24 with a controller running this branch: two robots detected and named from their LH2 fixes, drawn in the console.